home *** CD-ROM | disk | FTP | other *** search
/ Aminet 30 / Aminet 30 (1999)(Schatztruhe)[!][Apr 1999].iso / Aminet / dev / misc / WHDLoad_dev.lha / WHDLoad / Autodoc / whdload.doc
Text File  |  1999-02-15  |  61KB  |  1,656 lines
  1. TABLE OF CONTENTS
  2.  
  3. WHDLoad/--Overview--
  4. WHDLoad/resload_Abort
  5. WHDLoad/resload_Control
  6. WHDLoad/WHDLTAG_CBAF_SET
  7. WHDLoad/WHDLTAG_CBSWITCH_SET
  8. WHDLoad/WHDLTAG_IOERR_GET
  9. WHDLoad/resload_CRC16
  10. WHDLoad/resload_Decrunch
  11. WHDLoad/resload_Delay
  12. WHDLoad/resload_DeleteFile
  13. WHDLoad/resload_DiskLoad
  14. WHDLoad/resload_DiskLoadDev
  15. WHDLoad/resload_FlushCache
  16. WHDLoad/resload_GetFileSize
  17. WHDLoad/resload_ListFiles
  18. WHDLoad/resload_LoadFile
  19. WHDLoad/resload_LoadFileDecrunch
  20. WHDLoad/resload_LoadFileOffset
  21. WHDLoad/resload_ProtectRead
  22. WHDLoad/resload_ProtectReadWrite
  23. WHDLoad/resload_ProtectRemove
  24. WHDLoad/resload_ProtectWrite
  25. WHDLoad/resload_Relocate
  26. WHDLoad/resload_SaveFile
  27. WHDLoad/resload_SaveFileOffset
  28. WHDLoad/resload_SetCACR
  29. WHDLoad.Slave/--Overview--
  30.  
  31. WHDLoad/--Overview--
  32.  
  33. The calling conventions for all functions are similar to the OS-Library-
  34. concept. Parameters are provided in registers (except "resload_Abort"),
  35. return codes comes in D0 (on some functions also in D1). After a function call
  36. the registers D0-D1/A0-A1 are destroyed (D0,D1 may contain a returncode) they
  37. are so called scratch registers. All other registers are preserved.
  38. The base of the JMP tower in WHDLoad is similar to a LibraryBase. In
  39. difference to the OS the base must not stand in A6 on calling a function, but
  40. it is recommend to call all functions relative to a address register like
  41.         move.l  (_resload,pc),a5
  42.         JMP     (resload_Decrunch,a5)
  43. The resload base is overgiven in A0 on calling the Slave first via
  44. ws_GameLoader (see chapter WHDLoad.Slave/--Overview--).
  45.  
  46.  
  47. explanation of some keywords used in this document:
  48.  
  49. Slave           the file which contains the interface code
  50.                 (see chapter WHDLoad.Slave/--Overview--)
  51.  
  52. DiskImage       a Floppy-disk stored as a file on Harddisk
  53.  
  54. BaseMem         the size of the memory used by the installed program
  55.                 this value is specified in the Slave : ws_BaseMemSize
  56.                 this is also the upper bound of chip-mem for the installed
  57.                 program
  58.  
  59. logical values used for returncodes (see dos/dos.i):
  60.  
  61. TRUE = -1 (or better <>0)
  62. FALSE = 0
  63.  
  64. WHDLoad/resload_Abort
  65.  
  66.    NAME
  67.         resload_Abort -- quit and return to operating system
  68.  
  69.    SYNOPSIS
  70.         resload_Abort( success, primary, secondary)
  71.                          (a7)    (4,a7)    (8,a7)
  72.                         ULONG    ULONG     ULONG
  73.  
  74.    FUNCTION
  75.         terminates the program and return to OS
  76.  
  77.    INPUTS
  78.         success -   the reason for terminating
  79.                     one of TDREASON_#? ,defined in "whdload.i"
  80.                     depending on this value WHDLoad will continue different
  81.                 TDREASON_OK
  82.                     a normal exit will performed
  83.                 TDREASON_DEBUG
  84.                     WHDLoad will make a memory dump to .whdl_memory and a
  85.                     register dump to .whdl_register after this it will exit
  86.                 TDREASON_#? (except the above)
  87.                     WHDLoad will show an requester which displays the reason
  88.                     of failure, the user can now choose between "Quit",
  89.                     "Restart" and "Make CoreDump"
  90.         primary -   the primary errorcode, depends on success/TDREASON_#?
  91.                     TDREASON_DOSREAD,TDREASON_DOSWRITE,TDREASON_DOSLIST,
  92.                     TDREASON_DISKLOAD,TDREASON_DISKLOADDEV
  93.                       --> dos-errorcode/trackdisk-errorcode
  94.                     TDREASON_DEBUG
  95.                       --> program counter (to write it to the register dump)
  96.         secondary - the secondary errorcode, depends on success/TDREASON_#?
  97.                     TDREASON_DOSREAD,TDREASON_DOSWRITE,TDREASON_DOSLIST
  98.                       --> pointer to filename
  99.                     TDREASON_DISKLOAD
  100.                       --> disk number
  101.                     TDREASON_DEBUG
  102.                       --> status register (to write it to the register dump)
  103.  
  104.    EXAMPLE
  105.         to simply quit:
  106.                 ;primary and secondary wont be needed
  107.                 move.l  #TDREASON_OK,-(a7)
  108.                 move.l  (_resload,pc),a0
  109.                 jmp     (resload_Abort,a0)
  110.         to quit because reading of a file has failed:
  111.                 move.l  a0,-(a7)                        ;a0 = filename
  112.                 move.l  d0,-(a7)                        ;d0 = doserror code
  113.                 move.l  #TDREASON_DOSREAD,-(a7)
  114.                 move.l  (_resload,pc),-(a7)
  115.                 add.l   #resload_Abort,(a7)
  116.                 rts
  117.  
  118.    RESULT
  119.         nothing because WHDLoad will never return from this call
  120.  
  121.    BUGS
  122.  
  123.    NOTE
  124.         this routine is the only which must called via JMP and not JSR,
  125.         because the parameters lies on the stack
  126.         (this has the advantage that if success==TDREASON_DEBUG the registers
  127.         can preserved)
  128.  
  129.    SEE ALSO
  130.         example slaves
  131.  
  132. WHDLoad/resload_Control
  133.  
  134.    NAME
  135.         resload_Control
  136.  
  137.    SYNOPSIS
  138.         success = resload_Control(tags)
  139.           D0                       A0
  140.          BOOL                    STRUCT
  141.  
  142.    FUNCTION
  143.         control function of WHDLoad, get variables from WHDLoad,
  144.         set variables in WHDLoad depending on the tags in the overgiven
  145.         taglist
  146.  
  147.    INPUTS
  148.         tags - pointer to a table of tagitems
  149.  
  150.         WHDLTAG_ATTNFLAGS_GET  - gets the AttnFlags from systems execbase
  151.         WHDLTAG_ECLOCKFREQ_GET - gets the EClockFrequency from systems
  152.                                  execbase
  153.         WHDLTAG_MONITOR_GET    - gets the used monitor, the value will be
  154.                                  eiter NTSC_MONITOR_ID or PAL_MONITOR_ID
  155.                                  (defined in graphics/modeid.i), the used
  156.                                  monitor depends on execbase.VBlankFrequency
  157.                                  and can set by the user via tooltypes
  158.                                  NTSC and PAL
  159.         WHDLTAG_BUTTONWAIT_GET - returns -1 if argument/tooltype ButtonWait
  160.                                  is set, otherwise returns 0
  161.         WHDLTAG_CUSTOM1_GET
  162.         WHDLTAG_CUSTOM2_GET
  163.         WHDLTAG_CUSTOM3_GET
  164.         WHDLTAG_CUSTOM4_GET
  165.         WHDLTAG_CUSTOM5_GET    - returns numerical value of argument/tooltype
  166.                                  Custom1 .. Custom5
  167.         WHDLTAG_CBSWITCH_SET   - sets callback function to execute on switch
  168.                                  to installed program
  169.         WHDLTAG_IOERR_GET      - returns dos error code of the last resload
  170.                                  function call
  171.         WHDLTAG_VERSION_GET    - returns WHDLoad major version number, can be
  172.                                  used to distinguish between different
  173.                                  versions
  174.         WHDLTAG_REVISION_GET   - returns WHDLoad minor version number, can be
  175.                                  used to distinguish between different
  176.                                  versions
  177.         WHDLTAG_BUILD_GET      - returns WHDLoad build number, can be used to
  178.                                  distinguish between different versions
  179.         WHDLTAG_TIME_GET       - returns a pointer to a filled whdload_time
  180.                                  structure as decribed in whdload.i
  181.  
  182.    EXAMPLE
  183.                 ...
  184.                 clr.l   -(a7)                           ;TAG_DONE
  185.                 clr.l   -(a7)                           ;data to fill
  186.                 move.l  #WHDLTAG_ATTNFLAGS_GET,-(a7)
  187.                 move.l  a7,a0
  188.                 move.l  (_resload,pc),a2
  189.                 jsr     (resload_Control,a2)
  190.                 move.w  (6,a7),d0                       ;D0 = AttnFlags
  191.                 lea     (12,a7),a7                      ;restore sp
  192.                 ...
  193.  
  194.    EXAMPLE
  195.                 ...
  196.                 lea     (_tags,pc),a0
  197.                 move.l  (_resload,pc),a2
  198.                 jsr     (resload_Control,a2)
  199.                 move.w  (_attn,pc),d0                   ;D0 = AttnFlags
  200.                 ...
  201.         _tags
  202.                 dc.l    WHDLTAG_MONITOR_GET
  203.         _mon    dc.l    0
  204.                 dc.l    WHDLTAG_ATTNFLAGS_GET
  205.                 dc.w    0                               ;padding
  206.         _attn   dc.w    0
  207.                 dc.l    0                               ;TAG_DONE
  208.  
  209.    RESULT
  210.         success is true if all tags in the taglist are correctly processed
  211.         GET items in the taglist are filled with the requested data
  212.  
  213.    BUGS
  214.  
  215.    NOTE
  216.         requires ws_Version >= 5
  217.  
  218.    SEE ALSO
  219.  
  220. WHDLoad/WHDLTAG_CBAF_SET
  221.  
  222.    NAME
  223.         WHDLTAG_CBAF_SET
  224.  
  225.    SYNOPSIS
  226.         cont, adr,  data = CBAF(mode, size,  pc,  adr,  data)
  227.          D0    A1    A2          D0    D1    A0    A1    A2
  228.         LONG  APTR  APTR        LONG  LONG  APTR  APTR  APTR
  229.  
  230.    FUNCTION
  231.         with this tag a function can be set which will executed from WHDLoad
  232.         when an access fault exception occurs which is not handled by WHDLoad
  233.         itself, it may be used to locate specific accesses in conjunction with
  234.         resload_Protect and to correct invalid accesses in the development
  235.         process
  236.         with this routine you can catch all access faults except:
  237.          - instruction stream faults
  238.          - blitterwait and blitsize checks
  239.         at the time this routine will be executed the interrupts are disabled
  240.         via the sr 
  241.         the routine MUST not change any register except the registers holding
  242.         a return value, it MUST return via RTS
  243.  
  244.    INPUTS
  245.         mode - transfer mode of the faulted access
  246.                 0 - read
  247.                 1 - modify (only 68040/060)
  248.                 2 - write
  249.         size - operand size of the attempted access
  250.                 1 - Byte
  251.                 2 - Word
  252.                 4 - LongWord
  253.         pc   - program counter of the instruction which has faulted
  254.         adr  - the address which has attempted to access
  255.         data - valid only on write operations, the given memory address
  256.                contains the data which has been tried to write
  257.  
  258.    RESULT
  259.         cont - how to continue
  260.                 0 - terminate, WHDLoad will show a requester notifying the
  261.                     access fault
  262.                 1 - proceed, the faulted access will be emulated by the
  263.                     handler inside great WHDLoad
  264.         adr  - in case of proceed the address which will be accessed
  265.         data - in case of proceed and a write operation a pointer to the data
  266.                which will be written
  267.  
  268.    EXAMPLE
  269.         if you want to get informed at which point the installed program 
  270.         writes the value 42 to the address $BABE, you can do this like this:
  271.                 ...
  272.                 clr.l   -(a7)                           ;TAG_DONE
  273.                 pea     (_af,pc)                        ;function
  274.                 move.l  #WHDLTAG_CBAF_SET,-(a7)
  275.                 move.l  a7,a0
  276.                 move.l  (_resload,pc),a2
  277.                 jsr     (resload_Control,a2)
  278.                 lea     (12,a7),a7                      ;restore sp
  279.                 moveq   #2,d0
  280.                 lea     ($BABE),a0
  281.                 jsr     (resload_ProtectWrite,a2)
  282.                 ...
  283.  
  284.      _af        cmp.l   #$BABE,a1                       ;correct address ?
  285.                 bne     .term
  286.                 cmp.w   #2,d1                           ;size
  287.                 bne     .term
  288.                 cmp.w   #42,(a2)
  289.                 beq     .term
  290.                 moveq   #1,d0                           ;proceed
  291.                 rts
  292.  
  293.     .term       moveq   #0,d0                           ;terminate
  294.                 rts
  295.  
  296.    EXAMPLE
  297.         if want you to redirect an access to $24 to the address $300, you can
  298.         do this like this:
  299.                 ...
  300.                 clr.l   -(a7)                           ;TAG_DONE
  301.                 pea     (_af,pc)                        ;function
  302.                 move.l  #WHDLTAG_CBAF_SET,-(a7)
  303.                 move.l  a7,a0
  304.                 move.l  (_resload,pc),a2
  305.                 jsr     (resload_Control,a2)
  306.                 lea     (12,a7),a7                      ;restore sp
  307.                 moveq   #4,d0
  308.                 lea     ($24),a0
  309.                 jsr     (resload_ProtectWrite,a2)
  310.                 ...
  311.  
  312.      _af        cmp.l   #$24,a1                         ;correct address ?
  313.                 bne     .term
  314.                 lea     ($300),a1
  315.                 moveq   #1,d0                           ;proceed
  316.                 rts
  317.  
  318.     .term       moveq   #0,d0                           ;terminate
  319.                 rts
  320.  
  321.  
  322.    BUGS
  323.         currently only supported on 68030
  324.  
  325.    NOTE
  326.         requires ws_Version >= 9
  327.         MUST not be used in public releases, for development process only
  328.  
  329.    SEE ALSO
  330.         resload_Control
  331.  
  332. WHDLoad/WHDLTAG_CBSWITCH_SET
  333.  
  334.    NAME
  335.         WHDLTAG_CBSWITCH_SET
  336.  
  337.    SYNOPSIS
  338.         to be used with resload_Control
  339.  
  340.    FUNCTION
  341.         with this tag a function can be set which will executed from WHDLoad
  342.         when it switches from the OS to the installed program, the aim is to
  343.         give a possebilty to fix the problem that some Custom registers are
  344.         destroyed during such a switch
  345.         at the time this routine will be executed all interrupts and dma's are
  346.         disabled and the installed programs memory is restored
  347.         the function MUST not change any register, MUST not use stack and MUST
  348.         return via "JMP (A0)"
  349.         known registers which will be destroyed during the switch between OS
  350.         and installed program are cop2lc, bltafwm and bltalwm, but perhaps
  351.         there are more of them
  352.  
  353.    INPUTS
  354.         pointer to a function to execute
  355.         a pointer equal 0 means that no callback function should be active
  356.  
  357.    EXAMPLE
  358.                 ...
  359.                 clr.l   -(a7)                           ;TAG_DONE
  360.                 pea     (_cbswitch,pc)                  ;function
  361.                 move.l  #WHDLTAG_CBSWITCH_SET,-(a7)
  362.                 move.l  a7,a0
  363.                 move.l  (_resload,pc),a2
  364.                 jsr     (resload_Control,a2)
  365.                 lea     (12,a7),a7                      ;restore sp
  366.                 ...
  367.  
  368.      _cbswitch  move.l  (_c2,pc),(_custom+cop2lc)
  369.                 jmp     (a0)
  370.  
  371.      _cb2       dc.l    $10e80
  372.  
  373.    RESULT
  374.         none
  375.  
  376.    BUGS
  377.  
  378.    NOTE
  379.         requires ws_Version >= 7
  380.  
  381.    SEE ALSO
  382.         resload_Control
  383.  
  384. WHDLoad/WHDLTAG_IOERR_GET
  385.  
  386.    NAME
  387.         WHDLTAG_IOERR_GET
  388.  
  389.    SYNOPSIS
  390.         to be used with resload_Control
  391.  
  392.    FUNCTION
  393.         this tag can be used to get the dos errorcode of the last called
  394.         resload function, all resload functions except resload_Control will
  395.         set/reset this error code
  396.         currently there are two resload functions which will set the error
  397.         code:
  398.             resload_GetFileSize
  399.                 if a file with the specified name cannot be opened via
  400.                 dos.Open, the error code will be set to the value returned
  401.                 from dos.IoErr, so the error code may contain values like
  402.                 ERROR_OBJECT_NOT_FOUND, ERROR_OBJECT_WRONG_TYPE,
  403.                 ERROR_READ_PROTECTED or similar stuff from dos/dos.i
  404.                 the errorcode can be used to distinguish between a file with
  405.                 size of 0 and a nonexistent file
  406.             resload_ListFiles
  407.                 if the specified buffer to fill is not large enough to hold
  408.                 all filenames from the scanned directory, the error code will
  409.                 be set to ERROR_NO_FREE_STORE
  410.  
  411.    INPUTS
  412.         none
  413.  
  414.    EXAMPLE
  415.                 ...
  416.                 clr.l   -(a7)                           ;TAG_DONE
  417.                 clr.l   -(a7)                           ;data to fill
  418.                 move.l  #WHDLTAG_IOERR_GET,-(a7)
  419.                 move.l  a7,a0
  420.                 move.l  (_resload,pc),a2
  421.                 jsr     (resload_Control,a2)
  422.                 move.l  (4,a7),d0                       ;D0 = IoErr
  423.                 lea     (12,a7),a7                      ;restore sp
  424.                 ...
  425.  
  426.    RESULT
  427.         none
  428.  
  429.    BUGS
  430.  
  431.    NOTE
  432.         requires ws_Version >= 8
  433.  
  434.    SEE ALSO
  435.         resload_Control
  436.  
  437. WHDLoad/resload_CRC16
  438.  
  439.    NAME
  440.         resload_CRC16 -- calculate ANSI conform 16 bit CRC checksum
  441.  
  442.    SYNOPSIS
  443.         checksum = resload_CRC16(length,address)
  444.            D0                      D0     A0
  445.          UWORD                   ULONG   APTR
  446.  
  447.    FUNCTION
  448.         calculate ANSI conform 16 bit CRC checksum
  449.         mostly used to difference between various program versions
  450.  
  451.    INPUTS
  452.         length  - length of area to calculate over
  453.         address - pointer to area
  454.  
  455.    EXAMPLE
  456.                 ...
  457.                 lea     $1000,a0
  458.                 move.l  #256,d0         ;256 bytes starting at $1000
  459.                 move.l  (_resload,pc),a2
  460.                 jsr     (resload_CRC16,a2)
  461.                 cmp.w   #$f2b7,d0
  462.                 bne     .false_version
  463.                 ...
  464.  
  465.    RESULT
  466.         checksum - 16 bit crc
  467.  
  468.    BUGS
  469.  
  470.    NOTE
  471.         requires ws_Version >= 3
  472.  
  473.    SEE ALSO
  474.  
  475. WHDLoad/resload_Decrunch
  476.  
  477.    NAME
  478.         resload_Decrunch -- decrunch(unpack) file in memory
  479.  
  480.    SYNOPSIS
  481.         size = resload_Decrunch(source, destination)
  482.          D0                       A0        A1
  483.         ULONG                    APTR      APTR
  484.  
  485.    FUNCTION
  486.         decrunch packed file in memory
  487.         at the moment supported is : "RNC\01", "RNC\02", "IMP!", "ATN!"
  488.  
  489.    INPUTS
  490.         source      - address of source
  491.         destination - destination address (can be equal to source)
  492.  
  493.    EXAMPLE
  494.  
  495.    RESULT
  496.         size - the size of the decrunched file or 0 if not crunched or
  497.                format not known
  498.  
  499.    BUGS
  500.  
  501.    NOTE
  502.  
  503.    SEE ALSO
  504.         resload_LoadFileDecrunch
  505.  
  506. WHDLoad/resload_Delay
  507.  
  508.    NAME
  509.         resload_Delay -- wait some time
  510.  
  511.    SYNOPSIS
  512.         resload_Delay(time)
  513.                        D0
  514.                       ULONG
  515.  
  516.    FUNCTION
  517.         wait the specified time or until a button is pressed, the left and
  518.         right mouse button (port 0) and the fire button (port 1) will be
  519.         checked, after the time is released or a button is pressed the
  520.         function will wait until all buttons has been released
  521.         the wait routine is based on the raster beam, but checks the current
  522.         display and will therefore wait the correct time on PAL and NTSC
  523.  
  524.    INPUTS
  525.         time - time to wait in 1/10 seconds
  526.  
  527.    EXAMPLE
  528.                 ...
  529.                 moveq   #30,d0                  ;3 seconds
  530.                 move.l  (_resload,pc),a2
  531.                 jsr     (resload_Delay,a2)
  532.                 ...
  533.  
  534.    RESULT
  535.         nothing, all registers are preserved
  536.  
  537.    BUGS
  538.  
  539.    NOTE
  540.         in difference to most others resload_#? function this routine is
  541.         granted to preserve all registers
  542.  
  543.    SEE ALSO
  544.  
  545. WHDLoad/resload_DeleteFile
  546.  
  547.    NAME
  548.         resload_Delete -- delete file
  549.  
  550.    SYNOPSIS
  551.         success,errorcode = resload_DeleteFile(name)
  552.           D0       D1                           A0
  553.          BOOL    ULONG                         CPTR
  554.  
  555.    FUNCTION
  556.         deletes the file or directory with the specified name from the
  557.         filesystem
  558.  
  559.    INPUTS
  560.         name - name of the file/directory to delete
  561.  
  562.    EXAMPLE
  563.                 ...
  564.                 lea     (_name,pc),a0
  565.                 move.l  (_resload,pc),a2
  566.                 jsr     (resload_DeleteFile,a2)
  567.                 ...
  568.         _name   dc.b    "C:WHDLoad",0
  569.  
  570.    RESULT
  571.         success   - TRUE on success
  572.         errorcode - 0 on success
  573.                     otherwise a dos-errorcode from dos.IoErr()
  574.         if WHDLF_NoError is set, the function only returns on success
  575.  
  576.    BUGS
  577.  
  578.    NOTE
  579.         requires ws_Version >= 8
  580.  
  581.    SEE ALSO
  582.  
  583. WHDLoad/resload_DiskLoad
  584.  
  585.    NAME
  586.         resload_DiskLoad -- load part from a diskimage
  587.  
  588.    SYNOPSIS
  589.         success,errorcode = resload_DiskLoad(offset,size,diskno,dest)
  590.           D0       D1                          D0    D1    D2    A0
  591.          BOOL    ULONG                        ULONG ULONG UBYTE APTR
  592.  
  593.    FUNCTION
  594.         load part from a diskimage
  595.  
  596.    INPUTS
  597.         offset - offset in diskimage (relative to the beginning)
  598.         size   - amount of bytes to read
  599.         diskno - disk number
  600.         dest   - destination address
  601.  
  602.    EXAMPLE
  603.                 ...
  604.                 move.l  #880*512,d0             ;from block 880
  605.                 move.l  #2*512,d1               ;2 blocks
  606.                 moveq   #1,d2                   ;disk 1
  607.                 lea     $80000,a0               ;destination
  608.                 move.l  (_resload,pc),a2
  609.                 jsr     (resload_LoadDisk,a2)
  610.                 ...
  611.  
  612.    RESULT
  613.         success   - TRUE on success
  614.         errorcode - 0 on success
  615.                     otherwise a dos-errorcode from dos.IoErr()
  616.         if WHDLF_NoError is set, the function only returns on success
  617.  
  618.    BUGS
  619.  
  620.    NOTE
  621.         the name of the images must be "disk." followed by the disk number
  622.         (ie "Disk.1")
  623.         the size of the diskimages is variable, a try to read outside the
  624.         image will create a seek error
  625.  
  626.    SEE ALSO
  627.  
  628. WHDLoad/resload_DiskLoadDev
  629.  
  630.    NAME
  631.         resload_DiskLoadDev -- load part from a physical (floppy) drive
  632.  
  633.    SYNOPSIS
  634.         success,errorcode = resload_DiskLoadDev(offset, size,  dest,  tags)
  635.           D0       D1                             D0     D1     A0     A1
  636.          BOOL    ULONG                          ULONG  ULONG  UBYTE  STRUCT
  637.  
  638.    FUNCTION
  639.         load a given amount of bytes from a floppy like device
  640.  
  641.    INPUTS
  642.         offset - offset on the disk (relative to the beginning)
  643.         size   - amount of bytes to read (at the moment this must be a
  644.                  multiple of 512 bytes)
  645.         dest   - destination address (at the moment this must be aligned
  646.                  to 512 bytes)
  647.         tags   - pointer to a taglist (at the moment there are no valid
  648.                  tags, so this must be NULL)
  649.  
  650.    EXAMPLE
  651.                 ...
  652.                 move.l  #880*512,d0             ;from block 880
  653.                 move.l  #2*512,d1               ;2 blocks
  654.                 lea     $80000,a0               ;destination
  655.                 sub.l   a1,a1                   ;tag list
  656.                 move.l  (_resload,pc),a2
  657.                 jsr     (resload_LoadDisk,a2)
  658.                 ...
  659.  
  660.    RESULT
  661.         success   - TRUE on success
  662.         errorcode - 0 on success
  663.                     otherwise a trackdisk errorcode
  664.         if WHDLF_NoError is set, the function only returns on success
  665.  
  666.    BUGS
  667.  
  668.    NOTE
  669.         requires ws_Version >= 2
  670.         this function should used only in installation slaves !
  671.         at the moment all (size,address) must be aligned to 512 bytes due the
  672.         restrictions of trackdisk.device
  673.         it is planned to improve the function so that any possible diskformat
  674.         is readable with it
  675.  
  676.    SEE ALSO
  677.  
  678. WHDLoad/resload_FlushCache
  679.  
  680.    NAME
  681.         resload_FluchCache -- clear caches
  682.  
  683.    SYNOPSIS
  684.         resload_FlushCache()
  685.  
  686.    FUNCTION
  687.         clear all caches
  688.  
  689.    INPUTS
  690.  
  691.    EXAMPLE
  692.  
  693.    RESULT
  694.  
  695.    BUGS
  696.  
  697.    NOTE
  698.         may be called from User or Supervisor mode
  699.         may be also called on 68000/68010
  700.         it uses CACR on 68020/68030 and CPUSHA BC on 68040/68060
  701.  
  702.    SEE ALSO
  703.         resload_FlushCache
  704.  
  705. WHDLoad/resload_GetFileSize
  706.  
  707.    NAME
  708.         resload_GetFileSize -- get size of a file
  709.  
  710.    SYNOPSIS
  711.         size = resload_GetFileSize(name)
  712.          D0                         A0
  713.         BOOL                       CPTR
  714.  
  715.    FUNCTION
  716.         get size of a file
  717.         can also be used to check if a file does exist
  718.  
  719.    INPUTS
  720.         name - a $0 terminated string, the path + name
  721.  
  722.    EXAMPLE
  723.         to check if a file exists
  724.                 ...
  725.                 lea     (_name),a0
  726.                 move.l  (_resload,pc),a2
  727.                 jsr     (resload_GetFileSize,a2)
  728.                 tst.l   d0
  729.                 bne     .exist
  730.                 ...
  731.  
  732.    RESULT
  733.         size - the size of the file, 0 if does not exist
  734.  
  735.    BUGS
  736.  
  737.    NOTE
  738.         this routine return the size from the filesystem, if the file is
  739.         cruched and will be loaded later via resload_LoadFileDecrunch
  740.         the size will be different, you have been warned !
  741.  
  742.    SEE ALSO
  743.         resload_ListFiles
  744.  
  745. WHDLoad/resload_ListFiles
  746.  
  747.    NAME
  748.         resload_ListFiles -- list filenames of a directory
  749.  
  750.    SYNOPSIS
  751.         amount,errorcode = resload_ListFiles(buffersize, name, buffer)
  752.           D0      D1                             D0       A0     A1
  753.         ULONG   ULONG                          ULONG     CPTR   APTR
  754.  
  755.    FUNCTION
  756.         write the names of all files in the specified directory to the
  757.         buffer, the filenames are separated with a 0-byte
  758.  
  759.    INPUTS
  760.         buffersize - the size of the buffer
  761.         name       - the name of the directory to scan
  762.         buffer     - pointer to the buffer (the buffer MUST lie inside
  763.                      the Slave)
  764.  
  765.    EXAMPLE
  766.                 ...
  767.                 move.l  #_bufend-_buf,d0
  768.                 lea     (_savepath,pc),a0
  769.                 lea     (_buf,pc),a1
  770.                 move.l  (_resload,pc),a2
  771.                 jsr     (resload_ListFiles,a2)
  772.                 ...
  773.  
  774.         _buf    ds.b    1000
  775.         _bufend
  776.         _savepath dc.b  "/save",0       ;this MUST be a relative path !
  777.  
  778.  
  779.    RESULT
  780.         amount    - amount of listed files in the buffer
  781.         errorcode - 0 on success
  782.                     otherwise a dos-errorcode from dos.IoErr()
  783.         if WHDLF_NoError is set, the function only returns on success
  784.  
  785.  
  786.    BUGS
  787.         if the buffer was to small you will NOT get an errorcode (the
  788.         buffer is filled as far as possible, amount is equal the
  789.         number of names in buffer)
  790.  
  791.    NOTE
  792.  
  793.    SEE ALSO
  794.  
  795. WHDLoad/resload_LoadFile
  796.  
  797.    NAME
  798.         resload_LoadFile -- Load specified file
  799.  
  800.    SYNOPSIS
  801.         length,errorcode = resload_LoadFile(name, address)
  802.           D0      D1                         A0      A1
  803.         ULONG    ULONG                      CPTR    APTR
  804.  
  805.    FUNCTION
  806.         load file to the given address
  807.  
  808.    INPUTS
  809.         name    - pointer to a $0 terminated string
  810.                   (the string may be located in BaseMem or in the Slave)
  811.         address - the address on which the file should loaded
  812.  
  813.    EXAMPLE
  814.                 lea     (_filename),a0
  815.                 lea     $1000.w,a1              ;destination
  816.                 move.l  (_resload,pc),a2
  817.                 jsr     (resload_LoadFile,a2)
  818.  
  819.    RESULT
  820.         length    - the size of the loaded file
  821.                     if an error occurs this is NULL
  822.         errorcode - 0 on success
  823.                     otherwise a dos-errorcode from dos.IoErr()
  824.         if WHDLF_NoError is set, the function only returns on success
  825.  
  826.    BUGS
  827.  
  828.    NOTE
  829.         caches are flushed after this call
  830.  
  831.    SEE ALSO
  832.         resload_LoadFileDecrunch
  833.  
  834. WHDLoad/resload_LoadFileDecrunch
  835.  
  836.    NAME
  837.         resload_LoadFileDecrunch -- Load specified file and unpack if crunched
  838.  
  839.    SYNOPSIS
  840.         length,errorcode = resload_LoadFileDecrunch(name, address)
  841.           D0      D1                                 A0      A1
  842.         ULONG    ULONG                              CPTR    APTR
  843.  
  844.    FUNCTION
  845.         load file to the given address and unpack if crunched
  846.  
  847.    INPUTS
  848.         name    - pointer to a $0 terminated string
  849.                   (the string may be located in BaseMem or in the Slave)
  850.         address - the address on which the file should loaded
  851.  
  852.    EXAMPLE
  853.                 lea     (_filename),a0
  854.                 lea     $1000.w,a1              ;destination
  855.                 move.l  (_resload,pc),a2
  856.                 jsr     (resload_LoadFileDecrunch,a2)
  857.                 tst.l   d0
  858.                 beq     .error
  859.  
  860.    RESULT
  861.         length    - the size of the loaded file
  862.                     if an error occurs this is 0
  863.         errorcode - 0 on success
  864.                     otherwise a dos-errorcode from dos.IoErr()
  865.         if WHDLF_NoError is set, the function only returns on success
  866.  
  867.    BUGS
  868.  
  869.    NOTE
  870.         caches are flushed after this call
  871.  
  872.    SEE ALSO
  873.         resload_LoadFile, resload_Decrunch
  874.  
  875. WHDLoad/resload_LoadFileOffset
  876.  
  877.    NAME
  878.         resload_LoadFileOffset -- Load data from file with offset
  879.  
  880.    SYNOPSIS
  881.         success,error = resload_LoadFileOffset(size, offset, name, address)
  882.           D0     D1                             D0     D1     A0      A1
  883.          BOOL   ULONG                          ULONG  ULONG  CPTR    APTR
  884.  
  885.    FUNCTION
  886.         load data from a file at given file offset
  887.  
  888.    INPUTS
  889.         size    - amount of bytes to read
  890.         offset  - in file to read from
  891.         name    - pointer to a 0 terminated string
  892.                   (the string may be located in BaseMem or in the Slave)
  893.         address - of the buffer to load data in
  894.  
  895.    EXAMPLE
  896.                 move.l  #512,d0                 ;size
  897.                 move.l  #$4000,d1               ;offset
  898.                 lea     (_save,pc),a0           ;name
  899.                 lea     $5ac20,a1               ;source
  900.                 move.l  (_resload,pc),a2
  901.                 jsr     (resload_LoadFileOffset,a2)
  902.                 rts
  903.  
  904.         _save   dc.b    "saved",0
  905.  
  906.    RESULT
  907.         success   - TRUE on success
  908.         errorcode - 0 on success
  909.                     otherwise a dos-errorcode from dos.IoErr()
  910.         if WHDLF_NoError is set, the function only returns on success
  911.  
  912.    BUGS
  913.  
  914.    NOTE
  915.         requires ws_Version >= 6
  916.  
  917.    SEE ALSO
  918.  
  919. WHDLoad/resload_ProtectRead
  920.  
  921.    NAME
  922.         resload_ProtectRead -- mark area as read protected
  923.  
  924.    SYNOPSIS
  925.         resload_ProtectRead(length, address)
  926.                               D0      A0
  927.                              ULONG   APTR
  928.  
  929.    FUNCTION
  930.         protect the marked area against reading by the processor
  931.  
  932.    INPUTS
  933.         length  - size of the memory area which will be protected
  934.         address - the start address of the memory area
  935.  
  936.         the area to protect must be located inside the BaseMem area
  937.  
  938.    EXAMPLE
  939.                 ...
  940.                 moveq   #4,d0                   ;one longword
  941.                 lea     $4070,a0                ;address
  942.                 move.l  (_resload,pc),a2
  943.                 jsr     (resload_ProtectRead,a2)
  944.                 ...
  945.  
  946.    RESULT
  947.         a "Exception 'Access Fault'" WHDLoad requester if the protected area
  948.         is accessed
  949.  
  950.    BUGS
  951.         the amount of different areas is currently limited to 16,
  952.         you must not protect the page where the SSP points to, if you do so
  953.         an Double Bus Fault will occure because the CPU will be unable to
  954.         write the exception stackframe, only reset will recover from a Double
  955.         Bus Fault
  956.         limitations on MC68020+MC68851:
  957.           this hardware is currently not supported
  958.         limitations on MC68030:
  959.           - 3-byte transfers are not supported (occuring on misaligned
  960.             longword accesses to page boundaries eg. "tst.l $fff")
  961.           - locked accesses (tas/cas/cas2) are not supported
  962.         limitations on MC68040:
  963.           this hardware is currently not supported
  964.         limitations on MC68060:
  965.           - misaligned access are not supported (a misaligned access is an
  966.             access which goes trough a page boundary, for example
  967.             "tst.l ($ffe)" (assumed 4KByte page size))
  968.           - locked transfers are not supported (tas/cas)
  969.           - instructions which lie on a protected page and access the
  970.             supervisor portion of the status register are executed wrong
  971.             (these instructions will always see the trace bit as 1 and the
  972.             interrupt level as 7, any modification of the supervisor portion
  973.             will have no effect)
  974.           - movem instruction may access a protected area without creating a
  975.             Access Fault exception (only the first bus cycle of the excution
  976.             unit will be verified for matching a protected area)
  977.           - move16 and double precision operations (FPU) are unsupported
  978.           - a "move (mem),(mem)" with overlapping source and destination
  979.             address which generates an Access Fault because Misalignment
  980.             will be executed wrong, for example "move.l ($ffc),($ffe)" where
  981.             page $1000..$1fff is protected and memory before execution
  982.             contains ($ffc)=$11112222,($1000)=$33334444, after execution
  983.             $1000 contains $11114444 and not $22224444)
  984.         unsupported accesses will result in a "Exception 'Access Fault'"
  985.         WHDLoad requester
  986.  
  987.    NOTE
  988.         requires ws_Version >= 6
  989.         the MMU must be in use by WHDLoad, otherwise you will get WHDLoad
  990.         requester "Unacceptible Arguments".
  991.         only accesses to the user and supervisor data stream are affected
  992.         (this means not affected are: cpu space accesses (eg getting values
  993.         from the vector table) and instruction stream accesses)
  994.  
  995.    SEE ALSO
  996.         resload_ProtectReadWrite, resload_ProtectWrite, resload_ProtectRemove
  997.  
  998. WHDLoad/resload_ProtectReadWrite
  999.  
  1000.    NAME
  1001.         resload_ProtectReadWrite -- mark area as read and write protected
  1002.  
  1003.    SYNOPSIS
  1004.         resload_ProtectReadWrite(length, address)
  1005.                                    D0      A0
  1006.                                   ULONG   APTR
  1007.  
  1008.    FUNCTION
  1009.         protect the selected area against reading and writing by the processor
  1010.  
  1011.    INPUTS
  1012.         length  - size of the memory area which will be protected
  1013.         address - the start address of the memory area
  1014.  
  1015.         the area to protect must be located inside the BaseMem area
  1016.  
  1017.    EXAMPLE
  1018.                 ...
  1019.                 moveq   #4,d0                   ;one longword
  1020.                 lea     $64,a0                  ;address
  1021.                 move.l  (_resload,pc),a2
  1022.                 jsr     (resload_ProtectReadWrite,a2)
  1023.                 ...
  1024.  
  1025.    RESULT
  1026.  
  1027.    BUGS
  1028.         the amount of different areas is currently limited to 16
  1029.         you must not protect the page where the SSP points to, if you do so
  1030.         an Double Bus Fault will occure because the CPU will be unable to
  1031.         write the exception stackframe, only reset will recover from a Double
  1032.         Bus Fault
  1033.         limitations on MC68020+MC68851:
  1034.           this hardware is currently not supported
  1035.         limitations on MC68030:
  1036.           - 3-byte transfers are not supported (occuring on misaligned
  1037.             longword accesses to page boundaries eg. "tst.l $fff")
  1038.           - locked accesses (tas/cas/cas2) are not supported
  1039.         limitations on MC68040:
  1040.           this hardware is currently not supported
  1041.         limitations on MC68060:
  1042.           - misaligned access are not supported (a misaligned access is an
  1043.             access which goes trough a page boundary, for example
  1044.             "tst.l ($ffe)" (assumed 4KByte page size))
  1045.           - locked transfers are not supported (tas/cas)
  1046.           - instructions which lie on a protected page and access the
  1047.             supervisor portion of the status register are executed wrong
  1048.             (these instructions will always see the trace bit as 1 and the
  1049.             interrupt level as 7, any modification of the supervisor portion
  1050.             will have no effect)
  1051.           - movem instruction may access a protected area without creating a
  1052.             Access Fault exception (only the first bus cycle of the excution
  1053.             unit will be verified for matching a protected area)
  1054.           - move16 and double precision operations (FPU) are unsupported
  1055.           - a "move (mem),(mem)" with overlapping source and destination
  1056.             address which generates an Access Fault because Misalignment
  1057.             will be executed wrong, for example "move.l ($ffc),($ffe)" where
  1058.             page $1000..$1fff is protected and memory before execution
  1059.             contains ($ffc)=$11112222,($1000)=$33334444, after execution
  1060.             $1000 contains $11114444 and not $22224444)
  1061.         unsupported accesses will result in a "Exception 'Access Fault'"
  1062.         WHDLoad requester
  1063.  
  1064.    NOTE
  1065.         requires ws_Version >= 6
  1066.         the MMU must be in use by WHDLoad, otherwise you will get WHDLoad
  1067.         requester "Unacceptible Arguments".
  1068.         only accesses to the user and supervisor data stream are affected
  1069.         (this means not affected are: cpu space accesses (eg getting values
  1070.         from the vector table) and instruction stream accesses)
  1071.  
  1072.    SEE ALSO
  1073.         resload_ProtectRead, resload_ProtectWrite, resload_ProtectRemove
  1074.  
  1075. WHDLoad/resload_ProtectRemove
  1076.  
  1077.    NAME
  1078.         resload_ProtectRemove -- remove protction from memory area
  1079.  
  1080.    SYNOPSIS
  1081.         resload_ProtectRemove(length, address)
  1082.                                 D0      A0
  1083.                                ULONG   APTR
  1084.  
  1085.    FUNCTION
  1086.         remove a previously created protection
  1087.  
  1088.    INPUTS
  1089.         length  - size of the memory area
  1090.         address - the start address of the memory area
  1091.  
  1092.         the area must exactly match the previously created area
  1093.  
  1094.    EXAMPLE
  1095.                 ...
  1096.                 moveq   #4,d0                   ;one longword
  1097.                 lea     $64,a0                  ;address
  1098.                 move.l  (_resload,pc),a2
  1099.                 jsr     (resload_ProtectRemove,a2)
  1100.                 ...
  1101.  
  1102.    RESULT
  1103.  
  1104.    BUGS
  1105.  
  1106.    NOTE
  1107.         requires ws_Version >= 6
  1108.  
  1109.    SEE ALSO
  1110.         resload_ProtectRead, resload_ProtectWrite, resload_ProtectWrite
  1111.  
  1112. WHDLoad/resload_ProtectWrite
  1113.  
  1114.    NAME
  1115.         resload_ProtectWrite -- mark area as write protected
  1116.  
  1117.    SYNOPSIS
  1118.         resload_ProtectWrite(length, address)
  1119.                                D0      A0
  1120.                               ULONG   APTR
  1121.  
  1122.    FUNCTION
  1123.         protect the selected area against writing by the processor
  1124.  
  1125.    INPUTS
  1126.         length  - size of the memory area which will be protected
  1127.         address - the start address of the memory area
  1128.  
  1129.         the area to protect must be located inside the BaseMem area
  1130.  
  1131.    EXAMPLE
  1132.                 ...
  1133.                 moveq   #4,d0                   ;one longword
  1134.                 lea     $64,a0                  ;address
  1135.                 move.l  (_resload,pc),a2
  1136.                 jsr     (resload_ProtectWrite,a2)
  1137.                 ...
  1138.  
  1139.    RESULT
  1140.  
  1141.    BUGS
  1142.         the amount of different areas is currently limited to 16
  1143.         you must not protect the page where the SSP points to, if you do so
  1144.         an Double Bus Fault will occure because the CPU will be unable to
  1145.         write the exception stackframe, only reset will recover from a Double
  1146.         Bus Fault
  1147.         limitations on MC68020+MC68851:
  1148.           this hardware is currently not supported
  1149.         limitations on MC68030:
  1150.           - 3-byte transfers are not supported (occuring on misaligned
  1151.             longword accesses to page boundaries eg. "tst.l $fff")
  1152.           - locked accesses (tas/cas/cas2) are not supported
  1153.         limitations on MC68040:
  1154.           this hardware is currently not supported
  1155.         limitations on MC68060:
  1156.           - misaligned access are not supported (a misaligned access is an
  1157.             access which goes trough a page boundary, for example
  1158.             "tst.l ($ffe)" (assumed 4KByte page size))
  1159.           - locked transfers are not supported (tas/cas)
  1160.           - instructions which lie on a protected page and access the
  1161.             supervisor portion of the status register are executed wrong
  1162.             (these instructions will always see the trace bit as 1 and the
  1163.             interrupt level as 7, any modification of the supervisor portion
  1164.             will have no effect)
  1165.           - movem instruction may access a protected area without creating a
  1166.             Access Fault exception (only the first bus cycle of the excution
  1167.             unit will be verified for matching a protected area)
  1168.           - move16 and double precision operations (FPU) are unsupported
  1169.           - a "move (mem),(mem)" with overlapping source and destination
  1170.             address which generates an Access Fault because Misalignment
  1171.             will be executed wrong, for example "move.l ($ffc),($ffe)" where
  1172.             page $1000..$1fff is protected and memory before execution
  1173.             contains ($ffc)=$11112222,($1000)=$33334444, after execution
  1174.             $1000 contains $11114444 and not $22224444)
  1175.         unsupported accesses will result in a "Exception 'Access Fault'"
  1176.         WHDLoad requester
  1177.  
  1178.    NOTE
  1179.         requires ws_Version >= 6
  1180.         the MMU must be in use by WHDLoad, otherwise you will get WHDLoad
  1181.         requester "Unacceptible Arguments".
  1182.         only accesses to the user and supervisor data stream are affected
  1183.         (this means not affected are: cpu space accesses (eg getting values
  1184.         from the vector table) and instruction stream accesses)
  1185.  
  1186.    SEE ALSO
  1187.         resload_ProtectRead, resload_ProtectReadWrite, resload_ProtectRemove
  1188.  
  1189. WHDLoad/resload_Relocate
  1190.  
  1191.    NAME
  1192.         resload_Relocate -- relocate an executable
  1193.  
  1194.    SYNOPSIS
  1195.         size = resload_Relocate(address, tags)
  1196.          D0                       A0      A1
  1197.         ULONG                    APTR   STRUCT
  1198.  
  1199.    FUNCTION
  1200.         relocate an standard AmigaDOS executable im memory
  1201.  
  1202.    INPUTS
  1203.         address - of the executable in memory, this is the source and also the
  1204.                   destination address, i.e. this function will relocates the
  1205.                   executable over itself (a multi stepping technique is used)
  1206.         tags    - currently there are no valid tags
  1207.  
  1208.    EXAMPLE
  1209.                 lea     (_main,pc),a0           ;name
  1210.                 lea     $400,a1                 ;source
  1211.                 move.l  (_resload,pc),a2
  1212.                 jsr     (resload_LoadFileDecrunch,a2)
  1213.                 lea     $400,a0                 ;address
  1214.                 sub.l   a1,a1                   ;tags
  1215.                 jsr     (resload_Relocate,a2)
  1216.                 ...
  1217.                 jmp     $400                    ;start the program
  1218.  
  1219.         _main   dc.b    "main-program",0
  1220.  
  1221.    RESULT
  1222.         size - length of the relocated executable
  1223.                (maybe be more or less than the executable file, depending on
  1224.                if there BSS hunks contained)
  1225.  
  1226.    BUGS
  1227.         the routine should support all Kick1.3 hunks except OVERLAY, anyway it
  1228.         is only tested with some simple executables, please report any
  1229.         problems or bugs
  1230.  
  1231.    NOTE
  1232.         currently the function uses ca 4100 bytes stack, perhaps that will
  1233.         decreased in the future
  1234.         currently the executabale must contain of not more than 256 hunks (the
  1235.         OS allows also only 256 hunks)
  1236.  
  1237.    SEE ALSO
  1238.  
  1239.  
  1240. WHDLoad/resload_SaveFile
  1241.  
  1242.    NAME
  1243.         resload_SaveFile -- Write buffer as file to disk
  1244.  
  1245.    SYNOPSIS
  1246.         success,errorcode = resload_SaveFile(size, name, address)
  1247.           D0       D1                         D0    A0      A1
  1248.          BOOL     ULONG                     ULONG  CPTR    APTR
  1249.  
  1250.    FUNCTION
  1251.         write buffer to disk
  1252.  
  1253.    INPUTS
  1254.         size    - amount of bytes to write
  1255.         name    - pointer to a $0 terminated string
  1256.                   (the string may be located in BaseMem or in the Slave)
  1257.         address - of the buffer
  1258.  
  1259.    EXAMPLE
  1260.                 move.l  #512,d0                 ;size
  1261.                 lea     (_save,pc),a0           ;name
  1262.                 lea     $5ac20,a1               ;source
  1263.                 move.l  (_resload,pc),a2
  1264.                 jsr     (resload_SaveFile,a2)
  1265.  
  1266.         _save   dc.b    "saved",0
  1267.  
  1268.    RESULT
  1269.         success   - TRUE on success
  1270.         errorcode - 0 on success
  1271.                     otherwise a dos-errorcode from dos.IoErr()
  1272.         if WHDLF_NoError is set, the function only returns on success
  1273.  
  1274.    BUGS
  1275.  
  1276.    NOTE
  1277.  
  1278.    SEE ALSO
  1279.         WHDLoad.Slave/--Overview--
  1280.  
  1281. WHDLoad/resload_SaveFileOffset
  1282.  
  1283.    NAME
  1284.         resload_SaveFileOffset -- Write buffer to a file
  1285.  
  1286.    SYNOPSIS
  1287.         success,error = resload_SaveFileOffset(size, offset, name, address)
  1288.           D0     D1                             D0     D1     A0      A1
  1289.          BOOL   ULONG                          ULONG  ULONG  CPTR    APTR
  1290.  
  1291.    FUNCTION
  1292.         write buffer to a file at given file offset
  1293.  
  1294.    INPUTS
  1295.         size    - amount of bytes to write
  1296.         offset  - in file to write
  1297.         name    - pointer to a 0 terminated string
  1298.                   (the string may be located in BaseMem or in the Slave)
  1299.         address - of the buffer
  1300.  
  1301.    EXAMPLE
  1302.                 move.l  #512,d0                 ;size
  1303.                 move.l  #$4000,d1               ;offset
  1304.                 lea     (_save,pc),a0           ;name
  1305.                 lea     $5ac20,a1               ;source
  1306.                 move.l  (_resload,pc),a2
  1307.                 jsr     (resload_SaveFileOffset,a2)
  1308.                 rts
  1309.  
  1310.         _save   dc.b    "saved",0
  1311.  
  1312.    RESULT
  1313.         success   - TRUE on success
  1314.         errorcode - 0 on success
  1315.                     otherwise a dos-errorcode from dos.IoErr()
  1316.         if WHDLF_NoError is set, the function only returns on success
  1317.  
  1318.    BUGS
  1319.  
  1320.    NOTE
  1321.         requires ws_Version >= 5
  1322.  
  1323.    SEE ALSO
  1324.  
  1325. WHDLoad/resload_SetCACR
  1326.  
  1327.    NAME
  1328.         resload_SetCACR -- setup cpu caches
  1329.  
  1330.    SYNOPSIS
  1331.         old = resload_SetCACR(new, mask)
  1332.         D0                     D0   D1
  1333.        ULONG                 ULONG ULONG
  1334.  
  1335.    FUNCTION
  1336.         modify the cpu caches via CACR (Cache Control Register) and
  1337.         the MMU tables if MMU is used by whdload
  1338.         for the address space of BaseMem (other areas may be also affected)
  1339.  
  1340.    INPUTS
  1341.         new  - new value for the cacr
  1342.         mask - the bits to change
  1343.         valid bits are (defined in exec/execbase.i)
  1344.                 CACRF_EnableI - instruction cache
  1345.                 CACRF_EnableD - data cache
  1346.  
  1347.    EXAMPLE
  1348.         to enable the instruction cache :
  1349.                 move.l  #CACRF_EnableI,d0       ;defined in exec/execbase.i
  1350.                 move.l  d0,d1
  1351.                 move.l  (_resload,pc),a2
  1352.                 jsr     (resload_SetCACR,a2)
  1353.                 lea     (_oldcacr,pc),a0
  1354.                 move.l  d0,(a0)                 ;if you need it later
  1355.                                                 ;(obsolete in most cases)
  1356.  
  1357.    RESULT
  1358.         old - the content before
  1359.  
  1360.    BUGS
  1361.  
  1362.    NOTE
  1363.         may be called from User or Supervisor mode
  1364.         may be also called on 68000/68010
  1365.         all caches are flushed on return
  1366.         if WHDLoad is launched with the option NOCACHE this routine will
  1367.         ignore the inputs (no caches can be enabled)
  1368.         you can enable the instruction cache (CACRF_EnableI) and the data
  1369.         cache (CACRF_EnableD), the data cache can only enabled if instruction
  1370.         cache is also enabled
  1371.         don't wonder if you see in the coredump or in a freezer that caches
  1372.         are enabled even if not enabled by the slave: if the mmu is used by
  1373.         whdload and no caches are switched on by the slave, whdload marks the
  1374.         BaseMem area using the mmu as nocacheable-serialized, and enables both
  1375.         caches so that the areas of whdload and the slave are still cachable
  1376.         to increase performance
  1377.         on the 68030 WriteAllocation is always enabled
  1378.  
  1379.    SEE ALSO
  1380.         resload_FlushCache
  1381.  
  1382. WHDLoad.Slave/--Overview--
  1383.  
  1384. The WHDload.Slave contains the interface code which makes the installed
  1385. program able to load his files from harddisk. Additional it should realize
  1386. the possibility to quit the program to return to the OS.
  1387.  
  1388.    FORMAT
  1389.         is a standard amiga executable
  1390.    DANGER
  1391.         the Slave MUST consist of only ONE hunk (ONE section)
  1392.         the Slave MUST be 100% PC-relative
  1393.    BACKGROUND
  1394.         the Slave must be accessible if the OS is active and also if the OS is
  1395.         off; therefore the Slave must placed outside the BaseMem area;
  1396.         if the Slave lies after loading in BaseMem (can only occur if no
  1397.         FastMem is available) WHDLoad will move the Slave to a other memory-
  1398.         location; this moving is the reason for "pc-relative" and
  1399.         "only one hunk"
  1400.  
  1401.    STRUCTURE
  1402.         at the top of the Slave is "WhdloadSlave" structure, after this
  1403.         follows the specific code and data
  1404.  
  1405.              STRUCTURE  WhdloadSlave,0
  1406.                 STRUCT  ws_Security,4
  1407.                 STRUCT  ws_ID,8
  1408.                 UWORD   ws_Version
  1409.                 UWORD   ws_Flags
  1410.                 ULONG   ws_BaseMemSize
  1411.                 ULONG   ws_ExecInstall
  1412.                 RPTR    ws_GameLoader
  1413.                 RPTR    ws_CurrentDir
  1414.                 RPTR    ws_DontCache
  1415.              (  LABEL   ws_SIZEOF_pre_v4  )
  1416.                 UBYTE   ws_keydebug
  1417.                 UBYTE   ws_keyexit
  1418.              (  LABEL   ws_SIZEOF_pre_v8  )
  1419.                 ULONG   ws_ExpMem
  1420.                 LABEL   ws_SIZEOF
  1421.  
  1422.         ws_Security
  1423.                 the code
  1424.                         moveq #-1,d0
  1425.                         rts
  1426.                 to avoid problems if somebody executes the Slave itself
  1427.  
  1428.         ws_ID
  1429.                 the string "WHDLOADS" for WHDLoad to check if it is a Slave
  1430.  
  1431.         (use the macro Slave_HEADER defined in whdload.i for ws_Security and
  1432.         ws_ID)
  1433.  
  1434.         ws_Version
  1435.                 the version of WHDLoad that is required by the Slave
  1436.                 some resload functions need at least a specific version of
  1437.                 WHDLoad, e.g. to use resload_CRC16 you must set ws_Version
  1438.                 to 3 or higher
  1439.                 on the other side the size of the WhdloadSlave structure
  1440.                 is different for different Slave versions, e.g. if you set
  1441.                 ws_Version to 4 or higher you MUST initialize the fields
  1442.                 ws_keydebug and ws_keyexit and so on
  1443.  
  1444.         ws_Flags
  1445.                 WHDLF_Disk / WHDLB_Disk
  1446.                    this flag should enabled if the program uses
  1447.                    disk images (the result is an different PRELOAD)
  1448.                    (starting whdload 0.143 it has no longer affect, but should
  1449.                    set because older WHDLoad version, and future changes)
  1450.                 WHDLF_NoError / WHDLB_NoError
  1451.                    if enabled every error occuring in a resload_#? function
  1452.                    lets WHDLoad immedately quit, and prompt an error requester
  1453.                    about the reason
  1454.                    so it is not neccessary that the Slave checks the return
  1455.                    code of a resload_#? function, it can be sure that if the
  1456.                    function returns it was successful (this will make the
  1457.                    slave much simpler)
  1458.                 WHDLF_EmulTrap / WHDLB_EmulTrap
  1459.                    this flag has only effect if the VBR is moved by WHDLoad
  1460.                    (i.e. the machine is at least a 68010 and the tooltype
  1461.                    NoVBRMove is not set)
  1462.                    if the flag is set all "trap #0..15"'s are emulated by the
  1463.                    exception handler in WHDLoad like the autovectors, i.e.
  1464.                    the handler checks if the vector ($80-$bc) is initialized
  1465.                    by the program, and if yes the routine will be called by
  1466.                    the handler
  1467.                 WHDLF_NoDivZero / WHDLB_NoDivZero
  1468.                    this flag has only effect if the VBR is moved by WHDLoad
  1469.                    (i.e. the machine is at least a 68010 and the tooltype
  1470.                    NoVBRMove is not set)
  1471.                    if the flag is set and a "Division by Zero" exception
  1472.                    occurs WHDLoad will not quit with an requester, but a
  1473.                    simple RTE will be performed
  1474.                    this maybe useful if you don't want use the option
  1475.                    NoVBRMove but the demo/game makes a lot of divisions by
  1476.                    zero and you are not able to patch them all
  1477.                 WHDLF_Req68020 / WHDLB_Req68020
  1478.                    this flag indicates that the Slave/installed program
  1479.                    requires at least a MC68020 cpu, WHDLoad will check at
  1480.                    startup if this requirement matches, if it doesn't the
  1481.                    program will be terminated with an appropriate requester
  1482.                 WHDLF_ReqAGA / WHDLB_ReqAGA
  1483.                    this flag indicates that the Slave/installed program
  1484.                    requires at least the AGA chipset, WHDLoad will check at
  1485.                    startup if this requirement matches, if it doesn't the
  1486.                    program will be terminated with an appropriate requester
  1487.                 WHDLF_NoKbd / WHDLB_NoKbd
  1488.                    this flag says WHDLoad, that it doesn't should reply the
  1489.                    keyboard if a key was pressed, this must be used with
  1490.                    programs which doesn't check the keyboard from the PORTS
  1491.                    interrupt ($68), background: in normal operation when
  1492.                    NoVBRMove is inactive, WHDLoad checks if a key was pressed
  1493.                    on each interrupt, if a key has been pressed it checks the
  1494.                    rawkey code against QuitKey, DebugKey and FreezeKey, if it
  1495.                    doesn't match it looks if there is a initialized PORTS
  1496.                    interrupt ($68), if there is no, it replies the keyboard
  1497.                    that the keycode has been received, therefore the installed
  1498.                    program if it checks the keyboard from e.g. the VBI will
  1499.                    never receive any keycode, this flag avoids this behavior
  1500.                 WHDLF_EmulLineA / WHDLB_EmulLineA
  1501.                    this flag has only effect if the VBR is moved by WHDLoad
  1502.                    (i.e. the machine is at least a 68010 and the tooltype
  1503.                    NoVBRMove is not set)
  1504.                    if the flag is set all exceptions "Line-A" (caused by
  1505.                    opcodes starting with %1010) are emulated by the
  1506.                    exception handler in WHDLoad like the autovectors, i.e.
  1507.                    the handler checks if the vector ($28) is initialized
  1508.                    by the program, and if it is the routine which the vector
  1509.                    points to will be called by the handler
  1510.                 WHDLF_EmulTrapV / WHDLB_EmulTrapV
  1511.                    this flag has only effect if the VBR is moved by WHDLoad
  1512.                    (i.e. the machine is at least a 68010 and the tooltype
  1513.                    NoVBRMove is not set)
  1514.                    if the flag is set all exceptions caused by a TrapV
  1515.                    instruction are emulated by the exception handler in 
  1516.                    WHDLoad like the autovectors, i.e. the handler checks if
  1517.                    the vector ($1C) is initialized by the program, and if it
  1518.                    is the routine which the vector points to will be called
  1519.                    by the handler
  1520.  
  1521.         ws_BaseMemSize
  1522.                 the size of the memory that is required by the program
  1523.                 the BaseMemory starts an $00000000 and ends at ws_BaseMemSize
  1524.                 (BaseMemory is always ChipMem)
  1525.                 this value must be multiple of $1000
  1526.                 the valid minimum is $2000 and maximum $200000
  1527.  
  1528.         ws_ExecInstall
  1529.                 no longer supported, must be set 0
  1530.  
  1531.         ws_GameLoader
  1532.                 a relative (to the start of the structure) 16-bit pointer
  1533.                 to the start code of the Slave
  1534.  
  1535.         ws_CurrentDir
  1536.                 a relative (to the start of the structure) 16-bit pointer
  1537.                 to a 0 terminated string which is the name of the path
  1538.                 where all files are stored (sub directory)
  1539.                 if no sub directory is used initialize this with 0
  1540.                 WHDLoad will change into this directory on startup
  1541.                 the path must be relative; you MUST NOT use any fucking lame
  1542.                 assignments
  1543.             BACKGROUND: if the assignment is not active on runtime the
  1544.                 dos.library will try to show a "Insert Disk ..." requester,
  1545.                 but intuition.library is locked, -> the system will hang
  1546.                 (deadlock) the user has only one alternative -> REBOOT
  1547.  
  1548.         ws_DontCache
  1549.                 a relative (to the start of the structure) 16-bit pointer
  1550.                 to a 0 terminated string which is a standard AmigaDos
  1551.                 pattern (dos.ParsePattern, dos.MatchPattern)
  1552.                 all files matching this pattern are not cached by WHDLoad
  1553.                 this may be useful for savegames
  1554.                 if you dont want to use set the entry to 0
  1555.                 starting WHDLoad version 0.107 this is no longer required,
  1556.                 because saved files are written to the cache, and if the
  1557.                 same file already exist it will replaced with the new,
  1558.                 anyway the functional is furthermore intact
  1559.  
  1560.       the following variables are only evaluated by whdload if ws_Version
  1561.       is set to >= 4
  1562.       the following variables MUST be initialized if you set ws_Version
  1563.       to >= 4
  1564.  
  1565.         ws_keydebug
  1566.                 the raw key code to exit with debug
  1567.                 this variable will be overwritten by WHDLoad if the option
  1568.                 DebugKey= is set in the global config or as CLI argument or
  1569.                 ToolType with the specified value from there
  1570.                 if the Slave provides an own handler to support a debug option
  1571.                 via the keyboard it should use this entry for comparision, so
  1572.                 it will be possible for the user to change the default key
  1573.                 suggestion from the slave
  1574.                 this entry is also used by WHDLoad's internal handler if the
  1575.                 VBR is moved (requires 68010+ and that NoVBRMove is not set)
  1576.                 (recommend is $58 = "F9")
  1577.  
  1578.         ws_keyexit
  1579.                 the raw key code to exit
  1580.                 similar to ws_keydebug
  1581.                 (recommend is $59 = "F10")
  1582.  
  1583.       the following variables are only evaluated by whdload if ws_Version
  1584.       is set to >= 8
  1585.       the following variables MUST be initialized if you set ws_Version
  1586.       to >= 8
  1587.  
  1588.         ws_ExpMem
  1589.                 if the installed program requires expansion memory, the size
  1590.                 must be specified here, WHDLoad will allocate a memory block
  1591.                 of this size and writes a pointer to the start of the
  1592.                 allocated memory back to this entry, the memory is granted to
  1593.                 be aligned to $1000 (4096 bytes), the size specified must be
  1594.                 an multiple of $1000 (4096), if WHDLoad fails to allocate
  1595.                 this memory it terminates with an appropriate error requester,
  1596.                 that means the slave will always get a valid pointer here
  1597.  
  1598.    CONVENTIONS for ws_GameLoader
  1599.         the status of the system at the moment of calling ws_GameLoader:
  1600.  
  1601.         CPU:
  1602.                 SR   = $2000           Supervisor-mode, all interrupts enabled
  1603.                 SSP  = ws_BaseMemSize  at end of BaseMem
  1604.                 USP  = SSP-$400        at end of BaseMem - 1024
  1605.                 A0   = ResidentLoader  pointer to the resident Jump-Tower
  1606.                 D0-D7/A1-A6 random     (D0=$d0d0d0d0 D1=...)
  1607.  
  1608.                 nothing more is interesting from the Slave programmes point of
  1609.                 view. you will program a virtual machine which is a plain
  1610.                 68000. all special registers like VBR,SFC,DFC,CAAR,CACR,MSP,
  1611.                 TC,MMUSR,CRP,SRP,URP,TT0,TT1,DTT0,DTT1,ITT0,ITT1,PCR,BUSCR
  1612.                 are WHDLoad private and MUST NOT BE CHANGED.
  1613.  
  1614.         BaseMem:
  1615.                 $00000000 = 0
  1616.                 $00000004 = $f0000001  any try to use the execbase should
  1617.                                        create a "Address Error" exception
  1618.                 $00000008 - $00000400
  1619.                           = $CCCCCCCC  if WHDLoad has moved the VBR else
  1620.                           = Handler    the address of a exception handler
  1621.                                        inside WHDLoad
  1622.                 $00000400 - ws_BaseMemSize
  1623.                           = $CCCCCCCC  this memory fill pattern is used to
  1624.                                        easy recognize modified memory
  1625.                 $00001000 = $FFFFFFFE  the copper instruction "CWAIT $ff,$1fe"
  1626.  
  1627.         ExpMem:
  1628.                 the memory is filled with the pattern "$DDDDDDDD"
  1629.  
  1630.         custom:
  1631.                 dmacon = 0             all dma's off
  1632.                 intena = 0             all interrupts off
  1633.                 cop1lc = cop2lc = $1000
  1634.                 a AGA-machine is switched to OCS
  1635.  
  1636.         cia's:
  1637.                 ------- ciaa ------     ------- ciab ------
  1638.                 pra in  = %00000000     pra in  = %00000000
  1639.                 pra out = %11111100     pra out = %11111000
  1640.                 ddra    = %00000011     ddra    = %11000000
  1641.                 prb in  = %00000000     prb in  = %00000000
  1642.                 prb out = %00000000     prb out = %11111111
  1643.                 ddrb    = %00000000     ddrb    = %11111111
  1644.                 ta      =     $21ff     ta      =     $ffff
  1645.                 tb      =     $21ff     tb      =     $ffff
  1646.                 event   =   $000000     event   =   $000000
  1647.                 alarm   =   $ffffff     alarm   = execbase.EClockFrequency
  1648.                 sdr     =       $00     sdr     =       $00
  1649.                 icr     = %00000000     icr     = %00000000
  1650.                 icm     = %00001000     icm     = %00000000
  1651.                 cra     = %00000000     cra     = %00000000
  1652.                 crb     = %00000000     crb     = %00000000
  1653.  
  1654.    SEE ALSO
  1655.         example Slaves
  1656.